home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 4: GNU Archives / Linux Cubed Series 4 - GNU Archives.iso / gnu / cvs-1.8 / cvs-1 / cvs-1.8.1 / doc / cvs.info-1 < prev    next >
Encoding:
GNU Info File  |  1996-05-06  |  49.5 KB  |  1,276 lines
  1. This is Info file cvs.info, produced by Makeinfo-1.63 from the input
  2. file ./cvs.texinfo.
  3.  
  4.    Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994
  5. Free Software Foundation, Inc.
  6.  
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.  
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided also
  13. that the section entitled "GNU General Public License" is included
  14. exactly as in the original, and provided that the entire resulting
  15. derived work is distributed under the terms of a permission notice
  16. identical to this one.
  17.  
  18.    Permission is granted to copy and distribute translations of this
  19. manual into another language, under the above conditions for modified
  20. versions, except that the section entitled "GNU General Public License"
  21. and this permission notice may be included in translations approved by
  22. the Free Software Foundation instead of in the original English.
  23.  
  24. 
  25. File: cvs.info,  Node: Top,  Next: Preface,  Up: (dir)
  26.  
  27.  
  28.  
  29.    This info manual describes how to use and administer CVS version
  30. 1.8.1.
  31.  
  32. * Menu:
  33.  
  34. * Preface::                     About this manual
  35. * What is CVS?::                What is CVS?
  36. * Basic concepts::              Basic concepts of revision management
  37. * A sample session::            A tour of basic CVS usage
  38. * Repository::                  Where all your sources are stored
  39. * Starting a new project::      Starting a project with CVS
  40. * Multiple developers::         How CVS helps a group of developers
  41. * Branches::                    Parallel development explained
  42. * Merging::                     How to move changes between branches
  43. * Recursive behavior::          CVS descends directories
  44. * Adding files::                Adding files to a module
  45. * Removing files::              Removing files from a module
  46. * Tracking sources::            Tracking third-party sources
  47. * Moving files::                Moving and renaming files
  48. * Moving directories::          Moving and renaming directories
  49. * History browsing::            Viewing the history of files in various ways
  50. * Keyword substitution::        CVS can include the revision inside the file
  51. * Binary files::                CVS can handle binary files
  52. * Revision management::         Policy questions for revision management
  53. * Invoking CVS::                Reference manual for CVS commands
  54. * Administrative files::        Reference manual for the Administrative files
  55. * Environment variables::       All environment variables which affect CVS
  56. * Troubleshooting::             Some tips when nothing works
  57. * Copying::                     GNU GENERAL PUBLIC LICENSE
  58. * Index::                       Index
  59.  
  60. 
  61. File: cvs.info,  Node: Preface,  Next: What is CVS?,  Prev: Top,  Up: Top
  62.  
  63. About this manual
  64. *****************
  65.  
  66.    Up to this point, one of the weakest parts of CVS has been the
  67. documentation.  CVS is a complex program.  Previous versions of the
  68. manual were written in the manual page format, which is not really well
  69. suited for such a complex program.
  70.  
  71.    When writing this manual, I had several goals in mind:
  72.  
  73.    * No knowledge of RCS should be necessary.
  74.  
  75.    * No previous knowledge of revision control software should be
  76.      necessary.  All terms, such as "revision numbers", "revision
  77.      trees" and "merging" are explained as they are introduced.
  78.  
  79.    * The manual should concentrate on the things CVS users want to do,
  80.      instead of what the CVS commands can do.  The first part of this
  81.      manual leads you through things you might want to do while doing
  82.      development, and introduces the relevant CVS commands as they are
  83.      needed.
  84.  
  85.    * Information should be easy to find.  In the reference manual in
  86.      the appendices almost all information about every CVS command is
  87.      gathered together.  There is also an extensive index, and a lot of
  88.      cross references.
  89.  
  90.    This manual was contributed by Signum Support AB in Sweden.  Signum
  91. is yet another in the growing list of companies that support free
  92. software.  You are free to copy both this manual and the CVS program.
  93. *Note Copying::, for the details.  Signum Support offers support
  94. contracts and binary distribution for many programs, such as CVS, GNU
  95. Emacs, the GNU C compiler and others.  Write to us for more information.
  96.  
  97.      Signum Support AB
  98.      Box 2044
  99.      S-580 02  Linkoping
  100.      Sweden
  101.      
  102.      Email: info@signum.se
  103.      Phone: +46 (0)13 - 21 46 00
  104.      Fax:   +46 (0)13 - 21 47 00
  105.  
  106.    Another company selling support for CVS is Cyclic Software, web:
  107. `http://www.cyclic.com/', email: `info@cyclic.com'.
  108.  
  109. * Menu:
  110.  
  111. * Checklist::
  112. * Credits::
  113. * BUGS::
  114.  
  115. 
  116. File: cvs.info,  Node: Checklist,  Next: Credits,  Up: Preface
  117.  
  118. Checklist for the impatient reader
  119. ==================================
  120.  
  121.    CVS is a complex system.  You will need to read the manual to be
  122. able to use all of its capabilities.  There are dangers that can easily
  123. be avoided if you know about them, and this manual tries to warn you
  124. about them.  This checklist is intended to help you avoid the dangers
  125. without reading the entire manual.  If you intend to read the entire
  126. manual you can skip this table.
  127.  
  128. Binary files
  129.      CVS can handle binary files, but you must have RCS release 5.5 or
  130.      later and a release of GNU diff that supports the `-a' flag
  131.      (release 1.15 and later are OK).  You must also configure both RCS
  132.      and CVS to handle binary files when you install them.
  133.  
  134.      Keword substitution can be a source of trouble with binary files.
  135.      *Note Keyword substitution::, for solutions.
  136.  
  137. The `admin' command
  138.      Uncareful use of the `admin' command can cause CVS to cease
  139.      working.  *Note admin::, before trying to use it.
  140.  
  141. 
  142. File: cvs.info,  Node: Credits,  Next: BUGS,  Prev: Checklist,  Up: Preface
  143.  
  144. Credits
  145. =======
  146.  
  147.    Roland Pesch, Cygnus Support <pesch@cygnus.com> wrote the manual
  148. pages which were distributed with CVS 1.3.  Appendix A and B contain
  149. much text that was extracted from them.  He also read an early draft of
  150. this manual and contributed many ideas and corrections.
  151.  
  152.    The mailing-list `info-cvs' is sometimes informative. I have
  153. included information from postings made by the following persons: David
  154. G. Grubbs <dgg@think.com>.
  155.  
  156.    Some text has been extracted from the man pages for RCS.
  157.  
  158.    The CVS FAQ (*note What is CVS?::.) by David G. Grubbs has been used
  159. as a check-list to make sure that this manual is as complete as
  160. possible.  (This manual does however not include all of the material in
  161. the FAQ).  The FAQ contains a lot of useful information.
  162.  
  163.    In addition, the following persons have helped by telling me about
  164. mistakes I've made: Roxanne Brunskill <rbrunski@datap.ca>, Kathy Dyer
  165. <dyer@phoenix.ocf.llnl.gov>, Karl Pingle <pingle@acuson.com>, Thomas A
  166. Peterson <tap@src.honeywell.com>, Inge Wallin <ingwa@signum.se>, Dirk
  167. Koschuetzki <koschuet@fmi.uni-passau.de> and Michael Brown
  168. <brown@wi.extrel.com>.
  169.  
  170. 
  171. File: cvs.info,  Node: BUGS,  Prev: Credits,  Up: Preface
  172.  
  173. BUGS
  174. ====
  175.  
  176.    This manual is known to have room for improvement.  Here is a list
  177. of known deficiencies:
  178.  
  179.    * In the examples, the output from CVS is sometimes displayed,
  180.      sometimes not.
  181.  
  182.    * The input that you are supposed to type in the examples should
  183.      have a different font than the output from the computer.
  184.  
  185.    * This manual should be clearer about what file permissions you
  186.      should set up in the repository, and about setuid/setgid.
  187.  
  188.    * Some of the chapters are not yet complete.  They are noted by
  189.      comments in the `cvs.texinfo' file.
  190.  
  191.    * This list is not complete.  If you notice any error, omission, or
  192.      something that is unclear, please send mail to
  193.      bug-cvs@prep.ai.mit.edu.
  194.  
  195.    I hope that you will find this manual useful, despite the
  196. above-mentioned shortcomings.
  197.  
  198.  
  199.                                                 Linkoping, October 1993
  200.                                                          Per Cederqvist
  201.  
  202. 
  203. File: cvs.info,  Node: What is CVS?,  Next: Basic concepts,  Prev: Preface,  Up: Top
  204.  
  205. What is CVS?
  206. ************
  207.  
  208.    CVS is a version control system.  Using it, you can record the
  209. history of your source files.
  210.  
  211.    For example, bugs sometimes creep in when software is modified, and
  212. you might not detect the bug until a long time after you make the
  213. modification.  With CVS, you can easily retrieve old versions to see
  214. exactly which change caused the bug.  This can sometimes be a big help.
  215.  
  216.    You could of course save every version of every file you have ever
  217. created.  This would however waste an enormous amount of disk space.
  218. CVS stores all the versions of a file in a single file in a clever way
  219. that only stores the differences between versions.
  220.  
  221.    CVS also helps you if you are part of a group of people working on
  222. the same project.  It is all too easy to overwrite each others' changes
  223. unless you are extremely careful.  Some editors, like GNU Emacs, try to
  224. make sure that the same file is never modified by two people at the
  225. same time.  Unfortunately, if someone is using another editor, that
  226. safeguard will not work.  CVS solves this problem by insulating the
  227. different developers from each other.  Every developer works in his own
  228. directory, and CVS merges the work when each developer is done.
  229.  
  230.    CVS started out as a bunch of shell scripts written by Dick Grune,
  231. posted to `comp.sources.unix' in the volume 6 release of December,
  232. 1986.  While no actual code from these shell scripts is present in the
  233. current version of CVS much of the CVS conflict resolution algorithms
  234. come from them.
  235.  
  236.    In April, 1989, Brian Berliner designed and coded CVS.  Jeff Polk
  237. later helped Brian with the design of the CVS module and vendor branch
  238. support.
  239.  
  240.    You can get CVS via anonymous ftp from a number of sites, for
  241. instance prep.ai.mit.edu in `pub/gnu'.
  242.  
  243.    There is a mailing list for CVS where bug reports can be sent,
  244. questions can be asked, an FAQ is posted, and discussion about future
  245. enhancements to CVS take place.  To submit a message to the list, write
  246. to <info-cvs@prep.ai.mit.edu>.  To subscribe or unsubscribe, write to
  247. <info-cvs-request@prep.ai.mit.edu>. Please be specific about your email
  248. address.
  249.  
  250. CVS is not...
  251. =============
  252.  
  253.    CVS can do a lot of things for you, but it does not try to be
  254. everything for everyone.
  255.  
  256. CVS is not a build system.
  257.      Though the structure of your repository and modules file interact
  258.      with your build system (e.g. `Makefile's), they are essentially
  259.      independent.
  260.  
  261.      CVS does not dictate how you build anything.  It merely stores
  262.      files for retrieval in a tree structure you devise.
  263.  
  264.      CVS does not dictate how to use disk space in the checked out
  265.      working directories.  If you write your `Makefile's or scripts in
  266.      every directory so they have to know the relative positions of
  267.      everything else, you wind up requiring the entire repository to be
  268.      checked out.  That's simply bad planning.
  269.  
  270.      If you modularize your work, and construct a build system that
  271.      will share files (via links, mounts, `VPATH' in `Makefile's,
  272.      etc.), you can arrange your disk usage however you like.
  273.  
  274.      But you have to remember that *any* such system is a lot of work
  275.      to construct and maintain.  CVS does not address the issues
  276.      involved.  You must use your brain and a collection of other tools
  277.      to provide a build scheme to match your plans.
  278.  
  279.      Of course, you should place the tools created to support such a
  280.      build system (scripts, `Makefile's, etc) under CVS.
  281.  
  282. CVS is not a substitute for management.
  283.      Your managers and project leaders are expected to talk to you
  284.      frequently enough to make certain you are aware of schedules,
  285.      merge points, branch names and release dates.  If they don't, CVS
  286.      can't help.
  287.  
  288.      CVS is an instrument for making sources dance to your tune.  But
  289.      you are the piper and the composer.  No instrument plays itself or
  290.      writes its own music.
  291.  
  292. CVS is not a substitute for developer communication.
  293.      When faced with conflicts within a single file, most developers
  294.      manage to resolve them without too much effort.  But a more
  295.      general definition of "conflict" includes problems too difficult
  296.      to solve without communication between developers.
  297.  
  298.      CVS cannot determine when simultaneous changes within a single
  299.      file, or across a whole collection of files, will logically
  300.      conflict with one another.  Its concept of a "conflict" is purely
  301.      textual, arising when two changes to the same base file are near
  302.      enough to spook the merge (i.e. `diff3') command.
  303.  
  304.      CVS does not claim to help at all in figuring out non-textual or
  305.      distributed conflicts in program logic.
  306.  
  307.      For example: Say you change the arguments to function `X' defined
  308.      in file `A'.  At the same time, someone edits file `B', adding new
  309.      calls to function `X' using the old arguments.  You are outside
  310.      the realm of CVS's competence.
  311.  
  312.      Acquire the habit of reading specs and talking to your peers.
  313.  
  314. CVS is not a configuration management system.
  315.      CVS is a source control system.  The phrase "configuration
  316.      management" is a marketing term, not an industry-recognized set of
  317.      functions.
  318.  
  319.      A true "configuration management system" would contain elements of
  320.      the following:
  321.  
  322.         * Source control.
  323.  
  324.         * Dependency tracking.
  325.  
  326.         * Build systems (i.e. What to build and how to find things
  327.           during a build.  What is shared?  What is local?)
  328.  
  329.         * Bug tracking.
  330.  
  331.         * Automated Testing procedures.
  332.  
  333.         * Release Engineering documentation and procedures.
  334.  
  335.         * Tape Construction.
  336.  
  337.         * Customer Installation.
  338.  
  339.         * A way for users to run different versions of the same
  340.           software on the same host at the same time.
  341.  
  342.      CVS provides only the first.
  343.  
  344.    This section is taken from release 2.3 of the CVS FAQ.
  345.  
  346. 
  347. File: cvs.info,  Node: Basic concepts,  Next: A sample session,  Prev: What is CVS?,  Up: Top
  348.  
  349. Basic concepts
  350. **************
  351.  
  352.    CVS stores all files in a centralized "repository": a directory
  353. (such as `/usr/local/cvsroot' or `user@remotehost:/usr/local/cvsroot')
  354. which is populated with a hierarchy of files and directories.  (*note
  355. Remote repositories::. for information about keeping the repository on
  356. a remote machine.)
  357.  
  358.    Normally, you never access any of the files in the repository
  359. directly.  Instead, you use CVS commands to get your own copy of the
  360. files, and then work on that copy.  When you've finished a set of
  361. changes, you check (or "commit") them back into the repository.
  362.  
  363.    The files in the repository are organized in "modules".  Each module
  364. is made up of one or more files, and can include files from several
  365. directories.  A typical usage is to define one module per project.
  366.  
  367. * Menu:
  368.  
  369. * Revision numbers::            The meaning of a revision number
  370. * Versions revisions releases::  Terminology used in this manual
  371.  
  372. 
  373. File: cvs.info,  Node: Revision numbers,  Next: Versions revisions releases,  Up: Basic concepts
  374.  
  375. Revision numbers
  376. ================
  377.  
  378.    Each version of a file has a unique "revision number".  Revision
  379. numbers look like `1.1', `1.2', `1.3.2.2' or even `1.3.2.2.4.5'.  A
  380. revision number always has an even number of period-separated decimal
  381. integers.  By default revision 1.1 is the first revision of a file.
  382. Each successive revision is given a new number by increasing the
  383. rightmost number by one.  The following figure displays a few
  384. revisions, with newer revisions to the right.
  385.  
  386.             +-----+    +-----+    +-----+    +-----+    +-----+
  387.             ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
  388.             +-----+    +-----+    +-----+    +-----+    +-----+
  389.  
  390.    CVS is not limited to linear development.  The "revision tree" can
  391. be split into "branches", where each branch is a self-maintained line of
  392. development.  Changes made on one branch can easily be moved back to
  393. the main trunk.
  394.  
  395.    Each branch has a "branch number", consisting of an odd number of
  396. period-separated decimal integers.  The branch number is created by
  397. appending an integer to the revision number where the corresponding
  398. branch forked off.  Having branch numbers allows more than one branch
  399. to be forked off from a certain revision.
  400.  
  401.    All revisions on a branch have revision numbers formed by appending
  402. an ordinal number to the branch number.  The following figure
  403. illustrates branching with an example.
  404.  
  405.                                                           +-------------+
  406.                                Branch 1.2.2.3.2 ->        ! 1.2.2.3.2.1 !
  407.                                                         / +-------------+
  408.                                                        /
  409.                                                       /
  410.                       +---------+    +---------+    +---------+    +---------+
  411.      Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !----! 1.2.2.4 !
  412.                     / +---------+    +---------+    +---------+    +---------+
  413.                    /
  414.                   /
  415.      +-----+    +-----+    +-----+    +-----+    +-----+
  416.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
  417.      +-----+    +-----+    +-----+    +-----+    +-----+
  418.                      !
  419.                      !
  420.                      !   +---------+    +---------+    +---------+
  421.      Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
  422.                          +---------+    +---------+    +---------+
  423.  
  424.    The exact details of how the branch number is constructed is not
  425. something you normally need to be concerned about, but here is how it
  426. works: When CVS creates a branch number it picks the first unused even
  427. integer, starting with 2.  So when you want to create a branch from
  428. revision 6.4 it will be numbered 6.4.2.  All branch numbers ending in a
  429. zero (such as 6.4.0) are used internally by CVS (*note Magic branch
  430. numbers::.).  The branch 1.1.1 has a special meaning.  *Note Tracking
  431. sources::.
  432.  
  433. 
  434. File: cvs.info,  Node: Versions revisions releases,  Prev: Revision numbers,  Up: Basic concepts
  435.  
  436. Versions, revisions and releases
  437. ================================
  438.  
  439.    A file can have several versions, as described above.  Likewise, a
  440. software product can have several versions.  A software product is
  441. often given a version number such as `4.1.1'.
  442.  
  443.    Versions in the first sense are called "revisions" in this document,
  444. and versions in the second sense are called "releases".  To avoid
  445. confusion, the word "version" is almost never used in this document.
  446.  
  447. 
  448. File: cvs.info,  Node: A sample session,  Next: Repository,  Prev: Basic concepts,  Up: Top
  449.  
  450. A sample session
  451. ****************
  452.  
  453.    This section describes a typical work-session using CVS.  It assumes
  454. that a repository is set up (*note Repository::.).
  455.  
  456.    Suppose you are working on a simple compiler.  The source consists
  457. of a handful of C files and a `Makefile'.  The compiler is called `tc'
  458. (Trivial Compiler), and the repository is set up so that there is a
  459. module called `tc'.
  460.  
  461. * Menu:
  462.  
  463. * Getting the source::          Creating a workspace
  464. * Committing your changes::     Making your work available to others
  465. * Cleaning up::                 Cleaning up
  466. * Viewing differences::         Viewing differences
  467.  
  468. 
  469. File: cvs.info,  Node: Getting the source,  Next: Committing your changes,  Up: A sample session
  470.  
  471. Getting the source
  472. ==================
  473.  
  474.    The first thing you must do is to get your own working copy of the
  475. source for `tc'.  For this, you use the `checkout' command:
  476.  
  477.      $ cvs checkout tc
  478.  
  479. This will create a new directory called `tc' and populate it with the
  480. source files.
  481.  
  482.      $ cd tc
  483.      $ ls tc
  484.      CVS         Makefile    backend.c   driver.c    frontend.c  parser.c
  485.  
  486.    The `CVS' directory is used internally by CVS.  Normally, you should
  487. not modify or remove any of the files in it.
  488.  
  489.    You start your favorite editor, hack away at `backend.c', and a
  490. couple of hours later you have added an optimization pass to the
  491. compiler.  A note to RCS and SCCS users: There is no need to lock the
  492. files that you want to edit.  *Note Multiple developers:: for an
  493. explanation.
  494.  
  495. 
  496. File: cvs.info,  Node: Committing your changes,  Next: Cleaning up,  Prev: Getting the source,  Up: A sample session
  497.  
  498. Committing your changes
  499. =======================
  500.  
  501.    When you have checked that the compiler is still compilable you
  502. decide to make a new version of `backend.c'.
  503.  
  504.      $ cvs commit backend.c
  505.  
  506. CVS starts an editor, to allow you to enter a log message.  You type in
  507. "Added an optimization pass.", save the temporary file, and exit the
  508. editor.
  509.  
  510.    The environment variable `$CVSEDITOR' determines which editor is
  511. started.  If `$CVSEDITOR' is not set, then if the environment variable
  512. `$EDITOR' is set, it will be used. If both `$CVSEDITOR' and `$EDITOR'
  513. are not set then the editor defaults to `vi'.  If you want to avoid the
  514. overhead of starting an editor you can specify the log message on the
  515. command line using the `-m' flag instead, like this:
  516.  
  517.      $ cvs commit -m "Added an optimization pass" backend.c
  518.  
  519. 
  520. File: cvs.info,  Node: Cleaning up,  Next: Viewing differences,  Prev: Committing your changes,  Up: A sample session
  521.  
  522. Cleaning up
  523. ===========
  524.  
  525.    Before you turn to other tasks you decide to remove your working
  526. copy of tc.  One acceptable way to do that is of course
  527.  
  528.      $ cd ..
  529.      $ rm -r tc
  530.  
  531. but a better way is to use the `release' command (*note release::.):
  532.  
  533.      $ cd ..
  534.      $ cvs release -d tc
  535.      M driver.c
  536.      ? tc
  537.      You have [1] altered files in this repository.
  538.      Are you sure you want to release (and delete) module `tc': n
  539.      ** `release' aborted by user choice.
  540.  
  541.    The `release' command checks that all your modifications have been
  542. committed.  If history logging is enabled it also makes a note in the
  543. history file.  *Note history file::.
  544.  
  545.    When you use the `-d' flag with `release', it also removes your
  546. working copy.
  547.  
  548.    In the example above, the `release' command wrote a couple of lines
  549. of output.  `? tc' means that the file `tc' is unknown to CVS.  That is
  550. nothing to worry about: `tc' is the executable compiler, and it should
  551. not be stored in the repository.  *Note cvsignore::, for information
  552. about how to make that warning go away.  *Note release output::, for a
  553. complete explanation of all possible output from `release'.
  554.  
  555.    `M driver.c' is more serious.  It means that the file `driver.c' has
  556. been modified since it was checked out.
  557.  
  558.    The `release' command always finishes by telling you how many
  559. modified files you have in your working copy of the sources, and then
  560. asks you for confirmation before deleting any files or making any note
  561. in the history file.
  562.  
  563.    You decide to play it safe and answer `n RET' when `release' asks
  564. for confirmation.
  565.  
  566. 
  567. File: cvs.info,  Node: Viewing differences,  Prev: Cleaning up,  Up: A sample session
  568.  
  569. Viewing differences
  570. ===================
  571.  
  572.    You do not remember modifying `driver.c', so you want to see what
  573. has happened to that file.
  574.  
  575.      $ cd tc
  576.      $ cvs diff driver.c
  577.  
  578.    This command runs `diff' to compare the version of `driver.c' that
  579. you checked out with your working copy.  When you see the output you
  580. remember that you added a command line option that enabled the
  581. optimization pass.  You check it in, and release the module.
  582.  
  583.      $ cvs commit -m "Added an optimization pass" driver.c
  584.      Checking in driver.c;
  585.      /usr/local/cvsroot/tc/driver.c,v  <--  driver.c
  586.      new revision: 1.2; previous revision: 1.1
  587.      done
  588.      $ cd ..
  589.      $ cvs release -d tc
  590.      ? tc
  591.      You have [0] altered files in this repository.
  592.      Are you sure you want to release (and delete) module `tc': y
  593.  
  594. 
  595. File: cvs.info,  Node: Repository,  Next: Starting a new project,  Prev: A sample session,  Up: Top
  596.  
  597. The Repository
  598. **************
  599.  
  600.    Figure 3 below shows a typical setup of a repository.  Only
  601. directories are shown below.
  602.  
  603.      /usr
  604.       |
  605.       +--local
  606.       |   |
  607.       |   +--cvsroot
  608.       |   |    |
  609.       |   |    +--CVSROOT
  610.                |      (administrative files)
  611.                |
  612.                +--gnu
  613.                |   |
  614.                |   +--diff
  615.                |   |   (source code to GNU diff)
  616.                |   |
  617.                |   +--rcs
  618.                |   |   (source code to RCS)
  619.                |   |
  620.                |   +--cvs
  621.                |       (source code to CVS)
  622.                |
  623.                +--yoyodyne
  624.                    |
  625.                    +--tc
  626.                    |    |
  627.                    |    +--man
  628.                    |    |
  629.                    |    +--testing
  630.                    |
  631.                    +--(other Yoyodyne software)
  632.  
  633.    There are a couple of different ways to tell CVS where to find the
  634. repository.  You can name the repository on the command line
  635. explicitly, with the `-d' (for "directory") option:
  636.  
  637.      cvs -d /usr/local/cvsroot checkout yoyodyne/tc
  638.  
  639.    Or you can set the `$CVSROOT' environment variable to an absolute
  640. path to the root of the repository, `/usr/local/cvsroot' in this
  641. example.  To set `$CVSROOT', all `csh' and `tcsh' users should have
  642. this line in their `.cshrc' or `.tcshrc' files:
  643.  
  644.      setenv CVSROOT /usr/local/cvsroot
  645.  
  646. `sh' and `bash' users should instead have these lines in their
  647. `.profile' or `.bashrc':
  648.  
  649.      CVSROOT=/usr/local/cvsroot
  650.      export CVSROOT
  651.  
  652.    A repository specified with `-d' will override the `$CVSROOT'
  653. environment variable.  Once you've checked a working copy out from the
  654. repository, it will remember where its repository is (the information
  655. is recorded in the `CVS/Root' file in the working copy).
  656.  
  657.    The `-d' option and the `CVS/Root' file both override the `$CVSROOT'
  658. environment variable; however, CVS will complain if the `-d' argument
  659. and the `CVS/Root' file disagree.
  660.  
  661.    There is nothing magical about the name `/usr/local/cvsroot'.  You
  662. can choose to place the repository anywhere you like.  *Note Remote
  663. repositories:: to learn how the repository can be on a different
  664. machine than your working copy of the sources.
  665.  
  666.    The repository is split in two parts.  `$CVSROOT/CVSROOT' contains
  667. administrative files for CVS.  The other directories contain the actual
  668. user-defined modules.
  669.  
  670. * Menu:
  671.  
  672. * User modules::                The structure of the repository
  673. * Intro administrative files::  Defining modules
  674. * Multiple repositories::       Multiple repositories
  675. * Creating a repository::       Creating a repository
  676. * Remote repositories::         Accessing repositories on remote machines
  677.  
  678. 
  679. File: cvs.info,  Node: User modules,  Next: Intro administrative files,  Up: Repository
  680.  
  681. User modules
  682. ============
  683.  
  684.        `$CVSROOT'
  685.          |
  686.          +--yoyodyne
  687.          |   |
  688.          |   +--tc
  689.          |   |   |
  690.                  +--Makefile,v
  691.                  +--backend.c,v
  692.                  +--driver.c,v
  693.                  +--frontend.c,v
  694.                  +--parser.c,v
  695.                  +--man
  696.                  |    |
  697.                  |    +--tc.1,v
  698.                  |
  699.                  +--testing
  700.                       |
  701.                       +--testpgm.t,v
  702.                       +--test2.t,v
  703.  
  704.    The figure above shows the contents of the `tc' module inside the
  705. repository.  As you can see all file names end in `,v'.  The files are
  706. "history files".  They contain, among other things, enough information
  707. to recreate any revision of the file, a log of all commit messages and
  708. the user-name of the person who committed the revision.  CVS uses the
  709. facilities of RCS, a simpler version control system, to maintain these
  710. files.  For a full description of the file format, see the `man' page
  711. `rcsfile(5)'.
  712.  
  713. * Menu:
  714.  
  715. * File permissions::            File permissions
  716.  
  717. 
  718. File: cvs.info,  Node: File permissions,  Up: User modules
  719.  
  720. File permissions
  721. ----------------
  722.  
  723.    All `,v' files are created read-only, and you should not change the
  724. permission of those files.  The directories inside the repository
  725. should be writable by the persons that have permission to modify the
  726. files in each directory.  This normally means that you must create a
  727. UNIX group (see group(5)) consisting of the persons that are to edit
  728. the files in a project, and set up the repository so that it is that
  729. group that owns the directory.
  730.  
  731.    This means that you can only control access to files on a
  732. per-directory basis.
  733.  
  734.    CVS tries to set up reasonable file permissions for new directories
  735. that are added inside the tree, but you must fix the permissions
  736. manually when a new directory should have different permissions than its
  737. parent directory.
  738.  
  739.    Since CVS was not written to be run setuid, it is unsafe to try to
  740. run it setuid.  You cannot use the setuid features of RCS together with
  741. CVS.
  742.  
  743. 
  744. File: cvs.info,  Node: Intro administrative files,  Next: Multiple repositories,  Prev: User modules,  Up: Repository
  745.  
  746. The administrative files
  747. ========================
  748.  
  749.    The directory `$CVSROOT/CVSROOT' contains some "administrative
  750. files".  *Note Administrative files::, for a complete description.  You
  751. can use CVS without any of these files, but some commands work better
  752. when at least the `modules' file is properly set up.
  753.  
  754.    The most important of these files is the `modules' file.  It defines
  755. all modules in the repository.  This is a sample `modules' file.
  756.  
  757.      CVSROOT         CVSROOT
  758.      modules         CVSROOT modules
  759.      cvs             gnu/cvs
  760.      rcs             gnu/rcs
  761.      diff            gnu/diff
  762.      tc              yoyodyne/tc
  763.  
  764.    The `modules' file is line oriented.  In its simplest form each line
  765. contains the name of the module, whitespace, and the directory where
  766. the module resides.  The directory is a path relative to `$CVSROOT'.
  767. The last for lines in the example above are examples of such lines.
  768.  
  769.    The line that defines the module called `modules' uses features that
  770. are not explained here.  *Note modules::, for a full explanation of all
  771. the available features.
  772.  
  773. Editing administrative files
  774. ----------------------------
  775.  
  776.    You edit the administrative files in the same way that you would edit
  777. any other module.  Use `cvs checkout CVSROOT' to get a working copy,
  778. edit it, and commit your changes in the normal way.
  779.  
  780.    It is possible to commit an erroneous administrative file.  You can
  781. often fix the error and check in a new revision, but sometimes a
  782. particularly bad error in the administrative file makes it impossible
  783. to commit new revisions.
  784.  
  785. 
  786. File: cvs.info,  Node: Multiple repositories,  Next: Creating a repository,  Prev: Intro administrative files,  Up: Repository
  787.  
  788. Multiple repositories
  789. =====================
  790.  
  791.    In some situations it is a good idea to have more than one
  792. repository, for instance if you have two development groups that work
  793. on separate projects without sharing any code.  All you have to do to
  794. have several repositories is to specify the appropriate repository,
  795. using the `CVSROOT' environment variable, the `-d' option to CVS, or
  796. (once you have checked out a working directories) by simply allowing
  797. CVS to use the repository that was used to check out the working
  798. directory (*note Repository::.).
  799.  
  800.    Notwithstanding, it can be confusing to have two or more
  801. repositories.
  802.  
  803.    None of the examples in this manual show multiple repositories.
  804.  
  805. 
  806. File: cvs.info,  Node: Creating a repository,  Next: Remote repositories,  Prev: Multiple repositories,  Up: Repository
  807.  
  808. Creating a repository
  809. =====================
  810.  
  811.    See the instructions in the `INSTALL' file in the CVS distribution.
  812.  
  813. 
  814. File: cvs.info,  Node: Remote repositories,  Prev: Creating a repository,  Up: Repository
  815.  
  816. Remote repositories
  817. ===================
  818.  
  819.    Your working copy of the sources can be on a different machine than
  820. the repository.  Generally, using a remote repository is just like
  821. using a local one, except that the format of the repository name is:
  822.  
  823.              user@hostname:/path/to/repository
  824.  
  825.    The details of exactly what needs to be set up depend on how you are
  826. connecting to the server.
  827.  
  828. * Menu:
  829.  
  830. * Connecting via rsh::          Using the `rsh' program to connect
  831. * Password authenticated::      Direct connections using passwords
  832. * Kerberos authenticated::      Direct connections with kerberos
  833.  
  834. 
  835. File: cvs.info,  Node: Connecting via rsh,  Next: Password authenticated,  Up: Remote repositories
  836.  
  837. Connecting with rsh
  838. -------------------
  839.  
  840.    CVS uses the `rsh' protocol to perform these operations, so the
  841. remote user host needs to have a `.rhosts' file which grants access to
  842. the local user.
  843.  
  844.    For example, suppose you are the user `mozart' on the local machine
  845. `anklet.grunge.com', and the server machine is
  846. `chainsaw.brickyard.com'.  On chainsaw, put the following line into the
  847. file `.rhosts' in `bach''s home directory:
  848.  
  849.      anklet.grunge.com  mozart
  850.  
  851.    Then test that `rsh' is working with
  852.  
  853.      rsh -l bach chainsaw.brickyard.com echo $PATH
  854.  
  855.    Next you have to make sure that `rsh' will be able to find the
  856. server.  Make sure that the path which `rsh' printed in the above
  857. example includes the directory containing a program named `cvs' which
  858. is the server.  You need to set the path in `.bashrc', `.cshrc', etc.,
  859. not `.login' or `.profile'.  Alternately, you can set the environment
  860. variable `CVS_SERVER' on the client machine to the filename of the
  861. server you want to use, for example `/usr/local/bin/cvs-1.6'.
  862.  
  863.    There is no need to edit `inetd.conf' or start a CVS server daemon.
  864.  
  865.    Continuing our example, supposing you want to access the module
  866. `foo' in the repository `/usr/local/cvsroot/', on machine
  867. `chainsaw.brickyard.com', you are ready to go:
  868.  
  869.      cvs -d bach@chainsaw.brickyard.com:/user/local/cvsroot checkout foo
  870.  
  871.    (The `bach@' can be omitted if the username is the same on both the
  872. local and remote hosts.)
  873.  
  874. 
  875. File: cvs.info,  Node: Password authenticated,  Next: Kerberos authenticated,  Prev: Connecting via rsh,  Up: Remote repositories
  876.  
  877. Direct connection with password authentication
  878. ----------------------------------------------
  879.  
  880.    The CVS client can also connect to the server using a password
  881. protocol.  This is particularly useful if using `rsh' is not feasible
  882. (for example, the server is behind a firewall), and Kerberos also is
  883. not available.
  884.  
  885.    To use this method, it is necessary to make some adjustments on both
  886. the server and client sides.
  887.  
  888. * Menu:
  889.  
  890. * Password authentication server::     Setting up the server
  891. * Password authentication client::     Using the client
  892. * Password authentication security::   What this method does and does not do
  893.  
  894. 
  895. File: cvs.info,  Node: Password authentication server,  Next: Password authentication client,  Up: Password authenticated
  896.  
  897. Setting up the server for password authentication
  898. .................................................
  899.  
  900.    On the server side, the file `/etc/inetd.conf' needs to be edited so
  901. `inetd' knows to run the command `cvs pserver' when it receives a
  902. connection on the right port.  By default, the port number is 2401; it
  903. would be different if your client were compiled with `CVS_AUTH_PORT'
  904. defined to something else, though.
  905.  
  906.    If your `inetd' allows raw port numbers in `/etc/inetd.conf', then
  907. the following (all on a single line in `inetd.conf') should be
  908. sufficient:
  909.  
  910.      2401  stream  tcp  nowait  root  /usr/local/bin/cvs
  911.      cvs -b /usr/local/bin pserver
  912.  
  913.    The `-b' option specifies the directory which contains the RCS
  914. binaries on the server.
  915.  
  916.    If your `inetd' wants a symbolic service name instead of a raw port
  917. number, then put this in `/etc/services':
  918.  
  919.      cvspserver      2401/tcp
  920.  
  921.    and put `cvspserver' instead of `2401' in `inetd.conf'.
  922.  
  923.    Once the above is taken care of, restart your `inetd', or do
  924. whatever is necessary to force it to reread its initialization files.
  925.  
  926.    Because the client stores and transmits passwords in cleartext
  927. (almost--see *Note Password authentication security:: for details), a
  928. separate CVS password file may be used, so people don't compromise their
  929. regular passwords when they access the repository.  This file is
  930. `$CVSROOT/CVSROOT/passwd' (*note Intro administrative files::.).  Its
  931. format is similar to `/etc/passwd', except that it only has two fields,
  932. username and password.  For example:
  933.  
  934.      bach:ULtgRLXo7NRxs
  935.      cwang:1sOp854gDF3DY
  936.  
  937.    The password is encrypted according to the standard Unix `crypt()'
  938. function, so it is possible to paste in passwords directly from regular
  939. Unix `passwd' files.
  940.  
  941.    When authenticating a password, the server first checks for the user
  942. in the CVS `passwd' file.  If it finds the user, it compares against
  943. that password.  If it does not find the user, or if the CVS `passwd'
  944. file does not exist, then the server tries to match the password using
  945. the system's user-lookup routine.  When using the CVS `passwd' file,
  946. the server runs under as the username specified in the the third
  947. argument in the entry, or as the first argument if there is no third
  948. argument (in this way CVS allows imaginary usernames provided the CVS
  949. `passwd' file indicates corresponding valid system usernames).  In any
  950. case, CVS will have no privileges which the (valid) user would not have.
  951.  
  952.    Right now, the only way to put a password in the CVS `passwd' file
  953. is to paste it there from somewhere else.  Someday, there may be a `cvs
  954. passwd' command.
  955.  
  956. 
  957. File: cvs.info,  Node: Password authentication client,  Next: Password authentication security,  Prev: Password authentication server,  Up: Password authenticated
  958.  
  959. Using the client with password authentication
  960. .............................................
  961.  
  962.    Before connecting to the server, the client must "log in" with the
  963. command `cvs login'.  Logging in verifies a password with the server,
  964. and also records the password for later transactions with the server.
  965. The `cvs login' command needs to know the username, server hostname,
  966. and full repository path, and it gets this information from the
  967. repository argument or the `CVSROOT' environment variable.
  968.  
  969.    `cvs login' is interactive -- it prompts for a password:
  970.  
  971.      cvs -d bach@chainsaw.brickyard.com:/usr/local/cvsroot login
  972.      CVS password:
  973.  
  974.    The password is checked with the server; if it is correct, the
  975. `login' succeeds, else it fails, complaining that the password was
  976. incorrect.
  977.  
  978.    Once you have logged in, you can force CVS to connect directly to
  979. the server and authenticate with the stored password by prefixing the
  980. repository with `:pserver:':
  981.  
  982.      cvs -d :pserver:bach@chainsaw.brickyard.com:/usr/local/cvsroot checkout foo
  983.  
  984.    The `:pserver:' is necessary because without it, CVS will assume it
  985. should use `rsh' to connect with the server (*note Connecting via
  986. rsh::.).  (Once you have a working copy checked out and are running CVS
  987. commands from within it, there is no longer any need to specify the
  988. repository explicitly, because CVS records it in the working copy's
  989. `CVS' subdirectory.)
  990.  
  991.    Passwords are stored by default in the file `$HOME/.cvspass'.  Its
  992. format is human-readable, but don't edit it unless you know what you
  993. are doing.  The passwords are not stored in cleartext, but are
  994. trivially encoded to protect them from "innocent" compromise (i.e.,
  995. inadvertently being seen by a system administrator who happens to look
  996. at that file).
  997.  
  998.    The `CVS_PASSFILE' environment variable overrides this default.  If
  999. you use this variable, make sure you set it *before* `cvs login' is
  1000. run.  If you were to set it after running `cvs login', then later CVS
  1001. commands would be unable to look up the password for transmission to
  1002. the server.
  1003.  
  1004.    The `CVS_PASSWORD' environment variable overrides *all* stored
  1005. passwords.  If it is set, CVS will use it for all password-authenticated
  1006. connections.
  1007.  
  1008. 
  1009. File: cvs.info,  Node: Password authentication security,  Prev: Password authentication client,  Up: Password authenticated
  1010.  
  1011. Security considerations with password authentication
  1012. ....................................................
  1013.  
  1014.    The passwords are stored on the client side in a trivial encoding of
  1015. the cleartext, and transmitted in the same encoding.  The encoding is
  1016. done only to prevent inadvertent password compromises (i.e., a system
  1017. administrator accidentally looking at the file), and will not prevent
  1018. even a naive attacker from gaining the password.
  1019.  
  1020.    The separate CVS password file (*note Password authentication
  1021. server::.) allows people to use a different password for repository
  1022. access than for login access.  On the other hand, once a user has
  1023. access to the repository, she can execute programs on the server system
  1024. through a variety of means.  Thus, repository access implies fairly
  1025. broad system access as well.  It might be possible to modify CVS to
  1026. prevent that, but no one has done so as of this writing.  Furthermore,
  1027. there may be other ways in which having access to CVS allows people to
  1028. gain more general access to the system; noone has done a careful audit.
  1029.  
  1030.    In summary, anyone who gets the password gets repository access, and
  1031. some measure of general system access as well.  The password is
  1032. available to anyone who can sniff network packets or read a protected
  1033. (i.e., user read-only) file.  If you want real security, get Kerberos.
  1034.  
  1035. 
  1036. File: cvs.info,  Node: Kerberos authenticated,  Prev: Password authenticated,  Up: Remote repositories
  1037.  
  1038. Direct connection with kerberos
  1039. -------------------------------
  1040.  
  1041.    The main disadvantage of using rsh is that all the data needs to
  1042. pass through additional programs, so it may be slower.  So if you have
  1043. kerberos installed you can connect via a direct TCP connection,
  1044. authenticating with kerberos (note that the data transmitted is *not*
  1045. encrypted).
  1046.  
  1047.    To do this, CVS needs to be compiled with kerberos support; when
  1048. configuring CVS it tries to detect whether kerberos is present or you
  1049. can use the `--with-krb4' flag to configure.
  1050.  
  1051.    You need to edit `inetd.conf' on the server machine to run `cvs
  1052. kserver'.  The client uses port 1999 by default; if you want to use
  1053. another port specify it in the `CVS_CLIENT_PORT' environment variable
  1054. on the client.  Set `CVS_CLIENT_PORT' to `-1' to force an rsh
  1055. connection.
  1056.  
  1057.    When you want to use CVS, get a ticket in the usual way (generally
  1058. `kinit'); it must be a ticket which allows you to log into the server
  1059. machine.  Then you are ready to go:
  1060.  
  1061.      cvs -d chainsaw.brickyard.com:/user/local/cvsroot checkout foo
  1062.  
  1063.    If CVS fails to connect, it will fall back to trying rsh.
  1064.  
  1065. 
  1066. File: cvs.info,  Node: Starting a new project,  Next: Multiple developers,  Prev: Repository,  Up: Top
  1067.  
  1068. Starting a project with CVS
  1069. ***************************
  1070.  
  1071.    Since CVS 1.x is bad at renaming files and moving them between
  1072. directories, the first thing you do when you start a new project should
  1073. be to think through your file organization.  It is not impossible--just
  1074. awkward--to rename or move files.  *Note Moving files::.
  1075.  
  1076.    What to do next depends on the situation at hand.
  1077.  
  1078. * Menu:
  1079.  
  1080. * Setting up the files::        Getting the files into the repository
  1081. * Defining the module::         How to make a module of the files
  1082.  
  1083. 
  1084. File: cvs.info,  Node: Setting up the files,  Next: Defining the module,  Up: Starting a new project
  1085.  
  1086. Setting up the files
  1087. ====================
  1088.  
  1089.    The first step is to create the files inside the repository.  This
  1090. can be done in a couple of different ways.
  1091.  
  1092. * Menu:
  1093.  
  1094. * From files::                  This method is useful with old projects
  1095.                                 where files already exists.
  1096. * From other version control systems::  Old projects where you want to
  1097.                                         preserve history from another system.
  1098. * From scratch::                Creating a module from scratch.
  1099.  
  1100. 
  1101. File: cvs.info,  Node: From files,  Next: From other version control systems,  Up: Setting up the files
  1102.  
  1103. Creating a module from a number of files
  1104. ----------------------------------------
  1105.  
  1106.    When you begin using CVS, you will probably already have several
  1107. projects that can be put under CVS control.  In these cases the easiest
  1108. way is to use the `import' command.  An example is probably the easiest
  1109. way to explain how to use it.  If the files you want to install in CVS
  1110. reside in `DIR', and you want them to appear in the repository as
  1111. `$CVSROOT/yoyodyne/DIR', you can do this:
  1112.  
  1113.      $ cd DIR
  1114.      $ cvs import -m "Imported sources" yoyodyne/DIR yoyo start
  1115.  
  1116.    Unless you supply a log message with the `-m' flag, CVS starts an
  1117. editor and prompts for a message.  The string `yoyo' is a "vendor tag",
  1118. and `start' is a "release tag".  They may fill no purpose in this
  1119. context, but since CVS requires them they must be present.  *Note
  1120. Tracking sources::, for more information about them.
  1121.  
  1122.    You can now verify that it worked, and remove your original source
  1123. directory.
  1124.  
  1125.      $ cd ..
  1126.      $ mv DIR DIR.orig
  1127.      $ cvs checkout yoyodyne/DIR       # Explanation below
  1128.      $ ls -R yoyodyne
  1129.      $ rm -r DIR.orig
  1130.  
  1131. Erasing the original sources is a good idea, to make sure that you do
  1132. not accidentally edit them in DIR, bypassing CVS.  Of course, it would
  1133. be wise to make sure that you have a backup of the sources before you
  1134. remove them.
  1135.  
  1136.    The `checkout' command can either take a module name as argument (as
  1137. it has done in all previous examples) or a path name relative to
  1138. `$CVSROOT', as it did in the example above.
  1139.  
  1140.    It is a good idea to check that the permissions CVS sets on the
  1141. directories inside `$CVSROOT' are reasonable, and that they belong to
  1142. the proper groups.  *Note File permissions::.
  1143.  
  1144. 
  1145. File: cvs.info,  Node: From other version control systems,  Next: From scratch,  Prev: From files,  Up: Setting up the files
  1146.  
  1147. Creating Files From Other Version Control Systems
  1148. -------------------------------------------------
  1149.  
  1150.    If you have a project which you are maintaining with another version
  1151. control system, such as RCS, you may wish to put the files from that
  1152. project into CVS, and preserve the revision history of the files.
  1153.  
  1154. From RCS
  1155.      If you have been using RCS, find the RCS files--usually a file
  1156.      named `foo.c' will have its RCS file in `RCS/foo.c,v' (but it
  1157.      could be other places; consult the RCS documentation for details).
  1158.      Then create the appropriate directories in CVS if they do not
  1159.      already exist.  Then copy the files into the appropriate
  1160.      directories in the CVS repository (the name in the repository must
  1161.      be the name of the source file with `,v' added; the files go
  1162.      directly in the appopriate directory of the repository, not in an
  1163.      `RCS' subdirectory).  This is one of the few times when it is a
  1164.      good idea to access the CVS repository directly, rather than using
  1165.      CVS commands.  Then you are ready to check out a new working
  1166.      directory.
  1167.  
  1168. From another version control system
  1169.      Many version control systems have the ability to export RCS files
  1170.      in the standard format.  If yours does, export the RCS files and
  1171.      then follow the above instructions.
  1172.  
  1173. From SCCS
  1174.      There is a script in the `contrib' directory of the CVS source
  1175.      distribution called `sccs2rcs' which converts SCCS files to RCS
  1176.      files.  Note: you must run it on a machine which has both SCCS and
  1177.      RCS installed, and like everything else in contrib it is
  1178.      unsupported (your mileage may vary).
  1179.  
  1180. 
  1181. File: cvs.info,  Node: From scratch,  Prev: From other version control systems,  Up: Setting up the files
  1182.  
  1183. Creating a module from scratch
  1184. ------------------------------
  1185.  
  1186.    For a new project, the easiest thing to do is probably to create an
  1187. empty directory structure, like this:
  1188.  
  1189.      $ mkdir tc
  1190.      $ mkdir tc/man
  1191.      $ mkdir tc/testing
  1192.  
  1193.    After that, you use the `import' command to create the corresponding
  1194. (empty) directory structure inside the repository:
  1195.  
  1196.      $ cd tc
  1197.      $ cvs import -m "Created directory structure" yoyodyne/DIR yoyo start
  1198.  
  1199.    Then, use `add' to add files (and new directories) as they appear.
  1200.  
  1201.    Check that the permissions CVS sets on the directories inside
  1202. `$CVSROOT' are reasonable.
  1203.  
  1204. 
  1205. File: cvs.info,  Node: Defining the module,  Prev: Setting up the files,  Up: Starting a new project
  1206.  
  1207. Defining the module
  1208. ===================
  1209.  
  1210.    The next step is to define the module in the `modules' file.  This
  1211. is not strictly necessary, but modules can be convenient in grouping
  1212. together related files and directories.
  1213.  
  1214.    In simple cases these steps are sufficient to define a module.
  1215.  
  1216.   1. Get a working copy of the modules file.
  1217.  
  1218.           $ cvs checkout modules
  1219.           $ cd modules
  1220.  
  1221.   2. Edit the file and insert a line that defines the module.  *Note
  1222.      Intro administrative files::, for an introduction.  *Note
  1223.      modules::, for a full description of the modules file.  You can
  1224.      use the following line to define the module `tc':
  1225.  
  1226.           tc   yoyodyne/tc
  1227.  
  1228.   3. Commit your changes to the modules file.
  1229.  
  1230.           $ cvs commit -m "Added the tc module." modules
  1231.  
  1232.   4. Release the modules module.
  1233.  
  1234.           $ cd ..
  1235.           $ cvs release -d modules
  1236.  
  1237. 
  1238. File: cvs.info,  Node: Multiple developers,  Next: Branches,  Prev: Starting a new project,  Up: Top
  1239.  
  1240. Multiple developers
  1241. *******************
  1242.  
  1243.    When more than one person works on a software project things often
  1244. get complicated.  Often, two people try to edit the same file
  1245. simultaneously.  Some other version control systems (including RCS and
  1246. SCCS) try to solve that particular problem by introducing "file
  1247. locking", so that only one person can edit each file at a time.
  1248. Unfortunately, file locking can be very counter-productive.  If two
  1249. persons want to edit different parts of a file, there may be no reason
  1250. to prevent either of them from doing so.
  1251.  
  1252.    CVS does not use file locking.  Instead, it allows many people to
  1253. edit their own "working copy" of a file simultaneously.  The first
  1254. person that commits his changes has no automatic way of knowing that
  1255. another has started to edit it.  Others will get an error message when
  1256. they try to commit the file.  They must then use CVS commands to bring
  1257. their working copy up to date with the repository revision.  This
  1258. process is almost automatic, and explained in this chapter.
  1259.  
  1260.    There are many ways to organize a team of developers.  CVS does not
  1261. try to enforce a certain organization.  It is a tool that can be used
  1262. in several ways.  It is often useful to inform the group of commits you
  1263. have done.  CVS has several ways of automating that process.  *Note
  1264. Informing others::.  *Note Revision management::, for more tips on how
  1265. to use CVS.
  1266.  
  1267. * Menu:
  1268.  
  1269. * File status::                 A file can be in several states
  1270. * Updating a file::             Bringing a file up-to-date
  1271. * Conflicts example::           An informative example
  1272. * Informing others::            To cooperate you must inform
  1273. * Concurrency::                 Simultaneous repository access
  1274. * Watches::                     Mechanisms to track who is editing files
  1275.  
  1276.